home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / libast / obj.h < prev    next >
C/C++ Source or Header  |  2005-10-18  |  29KB  |  763 lines
  1. /*
  2.  * Copyright (C) 1997-2004, Michael Jennings
  3.  *
  4.  * Permission is hereby granted, free of charge, to any person obtaining a copy
  5.  * of this software and associated documentation files (the "Software"), to
  6.  * deal in the Software without restriction, including without limitation the
  7.  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  8.  * sell copies of the Software, and to permit persons to whom the Software is
  9.  * furnished to do so, subject to the following conditions:
  10.  *
  11.  * The above copyright notice and this permission notice shall be included in
  12.  * all copies of the Software, its documentation and marketing & publicity
  13.  * materials, and acknowledgment shall be given in the documentation, materials
  14.  * and software packages that this Software was used.
  15.  *
  16.  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  17.  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  18.  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
  19.  * THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
  20.  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  21.  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  22.  */
  23.  
  24. #ifndef _LIBAST_OBJ_H_
  25. #define _LIBAST_OBJ_H_
  26.  
  27.  
  28. /**
  29.  * @file obj.h
  30.  * LibAST Object Infrastructure -- Generic Objects
  31.  *
  32.  * This file contains macros and type definitions for creating and
  33.  * manipulating basic generic objects.
  34.  *
  35.  * @author Michael Jennings <mej@eterm.org>
  36.  * $Revision: 1.29 $
  37.  * $Date: 2004/07/16 23:22:18 $
  38.  */
  39.  
  40. /*@{*/
  41. /**
  42.  * @name Object Definition and Declaration Macros
  43.  * ---
  44.  *
  45.  * This set of macros is intended to abstract certain details about
  46.  * the internal workings of objects and greatly simplify their
  47.  * definition.  The results have been known to cause non-cpp-compliant
  48.  * parsers to have the occasional fit, but they work. :-)
  49.  *
  50.  * @ingroup DOXGRP_OBJ
  51.  */
  52.  
  53. /**
  54.  * Declare an object structure.
  55.  *
  56.  * This macro abstracts the actual name of the object structure to
  57.  * help prevent its direct use.  Obviously the translation is plainly
  58.  * visible, so those sufficiently determined to do it the Wrong Way
  59.  * still can.  This macro is not used directly, but rather as part of
  60.  * the SPIF_DECL_OBJ() macro (see below), which is in turn used to
  61.  * define object types.
  62.  *
  63.  * @param t The object type as a non-quoted string (e.g., obj).
  64.  * @return  The @c struct keyword followed by the structure name for
  65.  *          the specified object type.
  66.  *
  67.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_DECL_OBJ(), SPIF_DECL_TYPE()
  68.  */
  69. #define SPIF_DECL_OBJ_STRUCT(t)  struct spif_ ## t ## _t_struct
  70.  
  71. /**
  72.  * Declare an object type based on the structure definition immediately
  73.  * following.
  74.  *
  75.  * This macro simplifies the creation of a new class by adding the
  76.  * appropriate @c typedef along with introducing the structure
  77.  * definition.  Although use of this macro presents a bit of an
  78.  * unnatural parsing problem for non-cpp-aware tools (e.g., indent),
  79.  * its use is recommended for encapsulation purposes.  Invocation of
  80.  * this macro should be immediately followed by an open brace ('{')
  81.  * and a normal C-style structure definition.
  82.  *
  83.  * @param t The object type as a non-quoted string (e.g., obj).
  84.  * @return  An appropriate @c typedef and @c struct introducer.
  85.  *
  86.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_DECL_TYPE(), SPIF_DECL_OBJ_STRUCT()
  87.  */
  88. #define SPIF_DECL_OBJ(t)  SPIF_DECL_TYPE(t, SPIF_DECL_OBJ_STRUCT(t)); SPIF_DECL_OBJ_STRUCT(t)
  89. /**
  90.  * Declare the parent type of an object being defined.
  91.  *
  92.  * This macro is used to declare that a particular object type (e.g.,
  93.  * obj) is the parent type of an object which is being defined via
  94.  * SPIF_DECL_OBJ().  The call to this macro should @em immediately
  95.  * follow the opening brace (which, in turn, immediately follows the
  96.  * call to SPIF_DECL_OBJ()).  Declaring the parent type allows for
  97.  * safe typecasting of any object of the current type to its parent
  98.  * type (or any parent type in its "family tree").  At minimum, any
  99.  * true object must at @em least be derived from the @c obj type so
  100.  * that it can be safely cast to a generic object.
  101.  *
  102.  * @param t The object type as a non-quoted string (e.g., obj).
  103.  *
  104.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_CONST_TYPE()
  105.  */
  106. #define SPIF_DECL_PARENT_TYPE(t)  SPIF_CONST_TYPE(t) parent
  107.  
  108. /**
  109.  * Declare the class variable for objects of a given type.
  110.  *
  111.  * Every object type has a class variable which is declared using this
  112.  * macro.  Any instance of that type of object contains a pointer to
  113.  * this same class variable.  This class variable is both declared and
  114.  * referenced using this macro so that its actual name is abstracted.
  115.  *
  116.  * @param type The object type as a non-quoted string (e.g., obj).
  117.  * @return     The class variable for the given type.
  118.  *
  119.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink
  120.  */
  121. #define SPIF_CLASS_VAR(type)  spif_ ## type ## _class
  122.  
  123. /**
  124.  * Declare a "property" of an object.
  125.  *
  126.  * This macro is used when declaring a class to specify that a
  127.  * particular class object is a "property."  A "property" is an object
  128.  * member which has public get/set methods of the same name.
  129.  *
  130.  * @param type The type of the property variable.
  131.  * @param name The name of the property.
  132.  *
  133.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink
  134.  */
  135. #define SPIF_DECL_PROPERTY(type, name)  SPIF_TYPE(type) name
  136.  
  137. /**
  138.  * Declare a "property" of an object.
  139.  *
  140.  * This macro is identical to SPIF_DECL_PROPERTY(), except that a
  141.  * native C type is used.
  142.  *
  143.  * @param type The C type of the property variable.
  144.  * @param name The name of the property.
  145.  *
  146.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_DECL_PROPERTY()
  147.  */
  148. #define SPIF_DECL_PROPERTY_C(type, name)  type name
  149.  
  150. /**
  151.  * Declare the get/set methods of a "property" of an object.
  152.  *
  153.  * This macro is used to prototype the get/set methods of an object
  154.  * property.
  155.  *
  156.  * @param otype The type of the object.
  157.  * @param vtype The type of the property variable.
  158.  * @param name  The name of the property.
  159.  *
  160.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink
  161.  */
  162. #define SPIF_DECL_PROPERTY_FUNC(otype, vtype, name)  \
  163.   SPIF_TYPE(vtype) spif_ ## otype ## _get_ ## name (SPIF_TYPE(otype)); \
  164.   SPIF_TYPE(bool) spif_ ## otype ## _set_ ## name (SPIF_TYPE(otype), SPIF_TYPE(vtype))
  165.  
  166. /**
  167.  * Declare the get/set methods of a "property" of an object.
  168.  *
  169.  * This macro is identical to SPIF_DECL_PROPERTY_FUNC(), except that a
  170.  * native C type is used.
  171.  *
  172.  * @param otype The type of the object.
  173.  * @param vtype The C type of the property variable.
  174.  * @param name  The name of the property.
  175.  *
  176.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_DECL_PROPERTY_FUNC()
  177.  */
  178. #define SPIF_DECL_PROPERTY_FUNC_C(otype, vtype, name)  \
  179.   vtype spif_ ## otype ## _get_ ## name (SPIF_TYPE(otype)); \
  180.   SPIF_TYPE(bool) spif_ ## otype ## _set_ ## name (SPIF_TYPE(otype), vtype)
  181.  
  182. /**
  183.  * Define the get/set methods of a "property" of an object.
  184.  *
  185.  * This macro is used to define (i.e., create, i.e. insert the code
  186.  * for) the get/set methods of an object property.
  187.  *
  188.  * @param otype The type of the object.
  189.  * @param vtype The type of the property variable.
  190.  * @param name  The name of the property.
  191.  *
  192.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink
  193.  */
  194. #define SPIF_DEFINE_PROPERTY_FUNC(otype, vtype, name)  \
  195.   SPIF_TYPE(vtype) spif_ ## otype ## _get_ ## name (SPIF_TYPE(otype) self) \
  196.     { return (self->name); } \
  197.   SPIF_TYPE(bool) spif_ ## otype ## _set_ ## name (SPIF_TYPE(otype) self, SPIF_TYPE(vtype) new_ ## name) \
  198.     { \
  199.         if (!SPIF_OBJ_ISNULL(self->name)) { \
  200.             SPIF_OBJ_DEL(self->name); \
  201.         } \
  202.         self->name = new_ ## name; \
  203.         return TRUE; \
  204.     }
  205.  
  206. /**
  207.  * Define the get/set methods of a "property" of an object.
  208.  *
  209.  * This macro is identical to SPIF_DEFINE_PROPERTY_FUNC(), except that
  210.  * the property is treated as a non-object (i.e., its current value is
  211.  * not checked, so no destructor is called for the current value).
  212.  * Use this for spif_*_t types that are not objects, such as
  213.  * spif_int32_t and spif_sockport_t.
  214.  *
  215.  * @param otype The type of the object.
  216.  * @param vtype The type of the property variable.
  217.  * @param name  The name of the property.
  218.  *
  219.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_DEFINE_PROPERTY_FUNC()
  220.  */
  221. #define SPIF_DEFINE_PROPERTY_FUNC_NONOBJ(otype, vtype, name)  \
  222.   SPIF_TYPE(vtype) spif_ ## otype ## _get_ ## name (SPIF_TYPE(otype) self) \
  223.     { return (self->name); } \
  224.   SPIF_TYPE(bool) spif_ ## otype ## _set_ ## name (SPIF_TYPE(otype) self, SPIF_TYPE(vtype) new_ ## name) \
  225.     { \
  226.         self->name = new_ ## name; \
  227.         return TRUE; \
  228.     }
  229.  
  230. /**
  231.  * Define the get/set methods of a "property" of an object.
  232.  *
  233.  * This macro is identical to SPIF_DEFINE_PROPERTY_FUNC(), except that
  234.  * a native C type is used.
  235.  *
  236.  * @param otype The type of the object.
  237.  * @param vtype The C type of the property variable.
  238.  * @param name  The name of the property.
  239.  *
  240.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_DEFINE_PROPERTY_FUNC()
  241.  */
  242. #define SPIF_DEFINE_PROPERTY_FUNC_C(otype, vtype, name)  \
  243.   vtype spif_ ## otype ## _get_ ## name (SPIF_TYPE(otype) self) \
  244.     { return (self->name); } \
  245.   SPIF_TYPE(bool) spif_ ## otype ## _set_ ## name (SPIF_TYPE(otype) self, vtype new_ ## name) \
  246.     { \
  247.         self->name = new_ ## name; \
  248.         return TRUE; \
  249.     }
  250. /*@}*/
  251.  
  252. /*@{*/
  253. /**
  254.  * @name Generic Object/Class Casting Macros
  255.  * ---
  256.  *
  257.  * This set of macros allows objects of any type (i.e., any object
  258.  * descended from the basic "obj" or "class" type) to be treated as
  259.  * generic object/class variables.  In other words, as long as an
  260.  * object is properly defined (i.e., properly descended from its basic
  261.  * type), it can be treated as that basic type via use of these
  262.  * macros.  The end result is that any operation which is defined for
  263.  * all objects can be executed on an object of any type without the
  264.  * need to know its exact type.
  265.  *
  266.  * @ingroup DOXGRP_OBJ
  267.  */
  268.  
  269. /**
  270.  * Cast an arbitrary class object to the generic class type.
  271.  *
  272.  * Most non-interface classes use the generic obj-style class
  273.  * variable, containing only the basic methods (create, delete,
  274.  * compare, etc.) that every object needs.  However, interface classes
  275.  * require the use of more specific class objects with support for
  276.  * additional object methods.  This macro allows an arbitrary class
  277.  * object, be it the generic class type or a decendent thereof, to be
  278.  * cast to the generic class type.  This allows basic method calls to
  279.  * be performed on complex types by treating them as simple objects.
  280.  *
  281.  * @param cls An arbitrary class object.
  282.  * @return    The class object cast to the generic type.
  283.  *
  284.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_OBJ_CLASS(), SPIF_CAST()
  285.  */
  286. #define SPIF_CLASS(cls)                  (SPIF_CAST(class) (cls))
  287.  
  288. /**
  289.  * Cast an arbitrary class object to a const generic class type.
  290.  *
  291.  * This macro is equivalent to SPIF_CLASS(), except that the resulting
  292.  * object is a @c const object.
  293.  *
  294.  * @param cls An arbitrary class object.
  295.  * @return    The class object cast to the generic type.
  296.  *
  297.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_CLASS(), SPIF_CONST_CAST()
  298.  */
  299. #define SPIF_CONST_CLASS(cls)            (SPIF_CONST_CAST(class) (cls))
  300.  
  301. /**
  302.  * Cast an arbitrary object to an obj.
  303.  *
  304.  * This macro allows an arbitrary object of any valid object type
  305.  * (i.e., anything derived from spif_obj_t) to be treated as a generic
  306.  * object (the spif_obj_t type).  Any method defined for generic
  307.  * objects (i.e., all objects) can be called on any object using a
  308.  * typecast such as this, and any function or macro which needs an
  309.  * arbitrary object can be passed any object using this macro.
  310.  *
  311.  * @param o An object of any valid type.
  312.  * @return  A generic object reference to that object.
  313.  *
  314.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_CAST()
  315.  */
  316. #define SPIF_OBJ(o)                    (SPIF_CAST(obj) (o))
  317. /*@}*/
  318.  
  319. /*@{*/
  320. /**
  321.  * @name Generic Object Type Safety Macros
  322.  * ---
  323.  *
  324.  * Macros in this group are used to verify the validity of an object
  325.  * instance and its type.
  326.  *
  327.  * @ingroup DOXGRP_OBJ
  328.  */
  329.  
  330. /**
  331.  * Determine if an arbitrary object is of type "obj."
  332.  *
  333.  * This macro returns a boolean value based on whether or not the
  334.  * object passed to it is of type "obj."  Obviously, this will almost
  335.  * never been the case, since the actual obj type is too generic to be
  336.  * useful for anything other than a parent class.  However, each
  337.  * object type needs to define a macro like this named
  338.  * SPIF_OBJ_IS_xxx() (where xxx is the object type), so this macro
  339.  * serves as a template for how those should be written.
  340.  *
  341.  * This type-verification class for each object type should always be
  342.  * defined as this one is -- simply a wrapper around
  343.  * SPIF_OBJ_IS_TYPE().
  344.  *
  345.  * @param o The object to test.
  346.  * @return  Whether or not the object is of type "obj."
  347.  *
  348.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_OBJ_IS_TYPE()
  349.  */
  350. #define SPIF_OBJ_IS_OBJ(o)               (SPIF_OBJ_IS_TYPE(o, obj))
  351.  
  352. /**
  353.  * Determine if an object of type "obj" is NULL.
  354.  *
  355.  * This macro returns a boolean value based on whether or not the
  356.  * object passed to it is NULL.  The object is cast to type "obj"
  357.  * before the comparison, so it should work for any valid object.
  358.  * This macro will not often be used by user code.  However, each
  359.  * object type needs to define a macro like this named
  360.  * SPIF_xxx_ISNULL() (where xxx is the object type), so this macro
  361.  * serves as a template for how those should be written.
  362.  *
  363.  * @param o The object to test.
  364.  * @return  Whether or not the object is NULL.
  365.  *
  366.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_OBJ(), SPIF_NULL_TYPE()
  367.  */
  368. #define SPIF_OBJ_ISNULL(o)               (SPIF_OBJ(o) == SPIF_NULL_TYPE(obj))
  369.  
  370. /**
  371.  * Determine if an object is of a given type.
  372.  *
  373.  * This macro returns a boolean value based on whether or not the
  374.  * given object, @a o, is of type @a type.  It provides the driving
  375.  * force behind all SPIF_OBJ_IS_xxx()-style macros.  Unlike the
  376.  * SPIF_OBJ_CHECK_TYPE() macro, this macro will @em always verify the
  377.  * object type.  If you need a debugging assertion instead, use
  378.  * SPIF_OBJ_CHECK_TYPE(), as it will resolve to @c (1) in
  379.  * non-debugging code.
  380.  *
  381.  * @param o    The object to test.
  382.  * @param type The type to check for.
  383.  * @return     Whether or not @a o is of type @a type.
  384.  *
  385.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_OBJ_ISNULL(), SPIF_OBJ_CLASS(),
  386.  *      SPIF_CLASS_VAR(), SPIF_OBJ_CHECK_TYPE()
  387.  */
  388. #define SPIF_OBJ_IS_TYPE(o, type)        ((!SPIF_OBJ_ISNULL(o)) && (SPIF_OBJ_CLASS(o) == SPIF_CLASS_VAR(type)))
  389.  
  390. /**
  391.  * Provide debugging assertion that an object is of a given type.
  392.  *
  393.  * This macro returns a boolean value based on whether or not the
  394.  * given object, @a o, is of type @a type.  It is intended for
  395.  * situations where the test only needs to be performed in debugging
  396.  * code.  If DEBUG is 0, it will resolve to @c (1).  If DEBUG is
  397.  * between 1 and 4 inclusive, it will simply be a NULL check.  Higher
  398.  * debug levels will treat it just like SPIF_OBJ_IS_TYPE().
  399.  *
  400.  * @param o    The object to test.
  401.  * @param type The type to check for.
  402.  * @return     Whether or not @a o is of type @a type.
  403.  *
  404.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_OBJ_ISNULL(), SPIF_OBJ_IS_TYPE()
  405.  */
  406. #if DEBUG == 0
  407. #  define SPIF_OBJ_CHECK_TYPE(o, type)   (1)
  408. #elif DEBUG <= 4
  409. #  define SPIF_OBJ_CHECK_TYPE(o, type)   (!SPIF_OBJ_ISNULL(o))
  410. #else
  411. #  define SPIF_OBJ_CHECK_TYPE(o, type)   SPIF_OBJ_IS_TYPE(o, type)
  412. #endif
  413. /*@}*/
  414.  
  415. /*@{*/
  416. /**
  417.  * @name Generic Object Instance Macros
  418.  * ---
  419.  *
  420.  * This set of macros manipulates actual object instances in various
  421.  * ways.  They can be used on any object.
  422.  *
  423.  * @ingroup DOXGRP_OBJ
  424.  */
  425.  
  426. /**
  427.  * Access the class for a given object.
  428.  *
  429.  * Every object has a member variable that references its class.
  430.  * There is a single class object for each individual object type, and
  431.  * all instances of that type reference the same class object.  If you
  432.  * know the type of an object, you can use SPIF_CLASS_VAR() to access
  433.  * its class object (i.e., the class object for that type).  However,
  434.  * this macro can be used to access the class object of @em any
  435.  * object, regardless of whether or not you know its type.
  436.  *
  437.  * @note This macro returns an object of type spif_class_t, so only
  438.  * methods common to all objects can be called using this macro.
  439.  * Other class types should define their own SPIF_xxx_CLASS() macro to
  440.  * access methods specific to that class.
  441.  *
  442.  * @param obj An object of arbitrary/unknown type.
  443.  * @return    The class object for the given object.
  444.  *
  445.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_CLASS(), SPIF_OBJ()
  446.  */
  447. #define SPIF_OBJ_CLASS(obj)              (SPIF_CLASS(SPIF_OBJ(obj)->cls))
  448.  
  449. /**
  450.  * Obtain the string representation of an object's class name.
  451.  *
  452.  * This macro will access the classname for an object.  The classname
  453.  * will be enclosed in exclamation marks ('!') so as to help identify
  454.  * its origin.  It is most often used as the return value for the
  455.  * @c type method of a given object type.
  456.  *
  457.  * @param obj An object of arbitrary/unknown type.
  458.  * @return    The class name (as a spif_classname_t) for the given
  459.  *            object.
  460.  *
  461.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_OBJ_CLASS()
  462.  */
  463. #define SPIF_OBJ_CLASSNAME(obj)          (SPIF_CAST(classname) SPIF_OBJ_CLASS(obj))
  464.  
  465. /**
  466.  * Call the named method for a given object.
  467.  *
  468.  * The methods which can be called on a given object are defined by
  469.  * that object's class.  Since all objects are derived from
  470.  * spif_obj_t, and all classes are derived from spif_class_t (the
  471.  * class type for "obj"), the methods defined by spif_class_t can be
  472.  * called on any arbitrary object, regardless of its actual
  473.  * object/class types.  This macro provides the mechanism by which
  474.  * this is done.
  475.  *
  476.  * @note This macro should not be called directly.  It is used by the
  477.  * SPIF_OBJ_*() macros and as a template for interface classes.
  478.  *
  479.  * @param obj  An object of arbitrary/unknown type.
  480.  * @param meth The name of the method to call.
  481.  * @return     A pointer to the specified method for that object.
  482.  *
  483.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_OBJ_CLASS()
  484.  */
  485. #define SPIF_OBJ_CALL_METHOD(obj, meth)  SPIF_OBJ_CLASS(obj)->meth
  486.  
  487. /**
  488.  * Create an instance of a generic object.
  489.  *
  490.  * This macro allocates and returns an object of type "obj."  Almost
  491.  * never used, but it's here for demonstration purposes anyway.
  492.  *
  493.  * @return An allocated object of type "obj."
  494.  *
  495.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, spif_obj_new()
  496.  */
  497. #define SPIF_OBJ_NEW()                   SPIF_CAST(obj) (SPIF_CLASS(SPIF_CLASS_VAR(obj)))->(noo)()
  498.  
  499. /**
  500.  * Initialize an object.
  501.  *
  502.  * This macro calls the @c init method of an object in order to
  503.  * initialize it.
  504.  *
  505.  * @param o An already-allocated object.
  506.  * @return  #TRUE if successful, #FALSE otherwise.
  507.  *
  508.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, spif_obj_init()
  509.  */
  510. #define SPIF_OBJ_INIT(o)                 SPIF_CAST(bool) (SPIF_OBJ_CALL_METHOD((o), init)(o))
  511.  
  512. /**
  513.  * Clean up an object.
  514.  *
  515.  * This macro calls the @c done method of an object.  This basically
  516.  * restores it to its original allocated-and-initialized state.
  517.  *
  518.  * @param o An object.
  519.  * @return  #TRUE if successful, #FALSE otherwise.
  520.  *
  521.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, spif_obj_done()
  522.  */
  523. #define SPIF_OBJ_DONE(o)                 SPIF_CAST(bool) (SPIF_OBJ_CALL_METHOD((o), done)(o))
  524.  
  525. /**
  526.  * Delete an object.
  527.  *
  528.  * This macro calls the @c del method of an object, destroying it and
  529.  * freeing its memory.
  530.  *
  531.  * @param o An object.  It will cease to exist after this call.
  532.  * @return  #TRUE if successful, #FALSE otherwise.
  533.  *
  534.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, spif_obj_del()
  535.  */
  536. #define SPIF_OBJ_DEL(o)                  SPIF_CAST(bool) (SPIF_OBJ_CALL_METHOD((o), del)(o))
  537.  
  538. /**
  539.  * Convert the contents of an object to a string.
  540.  *
  541.  * This macro calls the @c show method of an object, returning a
  542.  * spif_str_t object containing its string representation.
  543.  *
  544.  * @param o The object to display.
  545.  * @param b An existing spif_str_t buffer to use.  If NULL, a new str
  546.  *          object will be created and returned.
  547.  * @param i Number of leading spaces to indent.
  548.  * @return  A str object containing the string representation of @a o.
  549.  *
  550.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, spif_obj_show(), SPIF_SHOW()
  551.  */
  552. #define SPIF_OBJ_SHOW(o, b, i)           SPIF_CAST(str) (SPIF_OBJ_CALL_METHOD((o), show)(o, #o, b, i))
  553.  
  554. /**
  555.  * Compare two objects.
  556.  *
  557.  * This macro calls the @c comp method of object #1 to compare the two
  558.  * objects.
  559.  *
  560.  * @param o1 Object #1.
  561.  * @param o2 Object #2.
  562.  * @return   A spif_cmp_t value containing the comparison result.
  563.  *
  564.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, spif_obj_comp(), spif_comp_t
  565.  */
  566. #define SPIF_OBJ_COMP(o1, o2)            SPIF_CAST(cmp) (SPIF_OBJ_CALL_METHOD((o1),  comp)(o1, o2))
  567.  
  568. /**
  569.  * Duplicate an object.
  570.  *
  571.  * This macro calls the @c dup method of an object.  A copy of the
  572.  * object is returned.
  573.  *
  574.  * @param o An object.
  575.  * @return  A duplicate of that object.
  576.  *
  577.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, spif_obj_dup()
  578.  */
  579. #define SPIF_OBJ_DUP(o)                  SPIF_CAST(obj) (SPIF_OBJ_CALL_METHOD((o), dup)(o))
  580.  
  581. /**
  582.  * Obtain the type of the object.
  583.  *
  584.  * This macro calls the @c type method of an object to obtain its
  585.  * classname.
  586.  *
  587.  * @param o An object.
  588.  * @return  The classname of that object.
  589.  *
  590.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, spif_obj_type(), SPIF_OBJ_CLASSNAME()
  591.  */
  592. #define SPIF_OBJ_TYPE(o)                 SPIF_CAST(classname) (SPIF_OBJ_CALL_METHOD((o), type)(o))
  593. /*@}*/
  594.  
  595.  
  596. /*@{*/
  597. /**
  598.  * @name Object Display Convenience Macros
  599.  * ---
  600.  *
  601.  * This set of macros simplifies the process of displaying (as a
  602.  * string) the contents of an object.  They can be used on any object.
  603.  *
  604.  * @ingroup DOXGRP_OBJ
  605.  */
  606.  
  607. /**
  608.  * Convenience macro for displaying an object.
  609.  *
  610.  * This macro provides an easy way to output the string
  611.  * representation of an object to a given file descriptor.  The macro
  612.  * itself handles the creation and deletion of the temporary @c str
  613.  * object required (hence the "convenience").
  614.  *
  615.  * @param o  The object to display.
  616.  * @param fd The file descriptor to display it on.
  617.  *
  618.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, spif_obj_show()
  619.  */
  620. #define SPIF_SHOW(o, fd)                 do { \
  621.                                            spif_str_t tmp__; \
  622.                                            tmp__ = SPIF_OBJ_SHOW(o, SPIF_NULL_TYPE(str), 0); \
  623.                                            fprintf(fd, "%s", SPIF_STR_STR(tmp__)); \
  624.                                            spif_str_del(tmp__); \
  625.                                          } while (0)
  626.  
  627. /**
  628.  * Convenience macro for displaying a NULL value for an object.
  629.  *
  630.  * Obviously, one cannot invoke the @c show method of a NULL object.
  631.  * This macro exists to provide a uniform way for object @c show
  632.  * methods to easily (and uniformly) display NULL objects.
  633.  *
  634.  * @param t   The type of the NULL object.
  635.  * @param n   The name of the NULL object (variable name).
  636.  * @param b   A str object to which to assign the result.
  637.  * @param i   Number of spaces to indent.
  638.  * @param tmp A char[] buffer of fixed size used for temporary
  639.  *            storage.
  640.  *
  641.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, spif_obj_show()
  642.  */
  643. #define SPIF_OBJ_SHOW_NULL(t, n, b, i, tmp)  do { \
  644.                                                memset(tmp, ' ', (i)); \
  645.                                                snprintf(SPIF_CAST_C(char *) tmp + (i), sizeof(tmp) - (i), \
  646.                                                         "(spif_" #t "_t) %s:  " SPIF_NULLSTR_TYPE(t) "\n", \
  647.                                                         NONULL(n)); \
  648.                                                if (SPIF_STR_ISNULL(b)) { \
  649.                                                  (b) = spif_str_new_from_ptr(SPIF_CAST(charptr) tmp); \
  650.                                                } else { \
  651.                                                  spif_str_append_from_ptr((b), SPIF_CAST(charptr) tmp); \
  652.                                                } \
  653.                                              } while (0)
  654.  
  655. /**
  656.  * Convenience macro for handling NULL objects in a comparison.
  657.  *
  658.  * This macro exists because I got tired of typing the same thing over
  659.  * and over again to handle comparisons where either object may be
  660.  * NULL.  You should have this at the start of all of your *_comp()
  661.  * functions. 
  662.  *
  663.  * @param s   The "self" (first) object.
  664.  * @param o   The "other" (second) object.
  665.  *
  666.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, spif_obj_comp()
  667.  */
  668. #define SPIF_OBJ_COMP_CHECK_NULL(s, o) do { \
  669.                                            if (SPIF_OBJ_ISNULL((s)) && SPIF_OBJ_ISNULL((o))) { \
  670.                                                return SPIF_CMP_EQUAL; \
  671.                                            } else if (SPIF_OBJ_ISNULL((s))) { \
  672.                                                return SPIF_CMP_LESS; \
  673.                                            } else if (SPIF_OBJ_ISNULL((o))) { \
  674.                                                return SPIF_CMP_GREATER; \
  675.                                            } \
  676.                                        } while (0)
  677. /*@}*/
  678.  
  679.  
  680. /*@{*/
  681. /**
  682.  * @name Basic Object Class Definitions
  683.  * ---
  684.  *
  685.  * These types form the foundation of the LibAST object hierarchy.
  686.  *
  687.  * @ingroup DOXGRP_OBJ
  688.  */
  689.  
  690. /**
  691.  * Object class structure.
  692.  *
  693.  * This class contains the object class structure.  It contains the
  694.  * string representation of the class name followed by a series of
  695.  * function pointers to the member functions for the class.  The basic
  696.  * class type contains methods that all objects require.  The
  697.  * structure members should not be accessed directly, but rather via
  698.  * the appropriate macros.
  699.  *
  700.  * @note Doxygen doesn't understand how to handle the macro-based
  701.  * class definition for this structure, so it thinks it's a function.
  702.  * It's actually a struct definition (spif_const_class_t) and a
  703.  * pointer definition (spif_class_t) as provided by the
  704.  * SPIF_DEFINE_OBJ() macro.
  705.  *
  706.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_OBJ_CALL_METHOD()
  707.  */
  708. SPIF_DECL_OBJ(class) {
  709.     /** Text representation of class name. */
  710.     spif_classname_t classname;
  711.  
  712.     spif_func_t noo;
  713.     spif_func_t init;
  714.     spif_func_t done;
  715.     spif_func_t del;
  716.     spif_func_t show;
  717.     spif_func_t comp;
  718.     spif_func_t dup;
  719.     spif_func_t type;
  720. };
  721.  
  722. /* An obj is the most basic object type.  It contains simply a pointer to
  723.    the class name (a const char * so you can test it with ==). */
  724.  
  725. /**
  726.  * Generic object structure.
  727.  *
  728.  * The @c obj type is the parent of all other object types.  Since it
  729.  * doesn't actually store any data, the only member of the @c obj
  730.  * type is its spif_class_t 
  731.  *
  732.  * @note Doxygen doesn't understand how to handle the macro-based
  733.  * class definition for this structure, so it thinks it's a function.
  734.  * It's actually a struct definition (spif_const_obj_t) and a pointer
  735.  * definition (spif_obj_t) as provided by the SPIF_DEFINE_OBJ()
  736.  * macro.
  737.  *
  738.  * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink
  739.  */
  740. SPIF_DECL_OBJ(obj) {
  741.     spif_class_t cls;
  742. };
  743. /*@}*/
  744.  
  745.  
  746.  
  747. /* We need typedef's from here... */
  748. #include <libast/str.h>
  749.  
  750. extern spif_class_t SPIF_CLASS_VAR(obj);
  751. extern spif_obj_t spif_obj_new(void);
  752. extern spif_bool_t spif_obj_del(spif_obj_t);
  753. extern spif_bool_t spif_obj_init(spif_obj_t);
  754. extern spif_bool_t spif_obj_done(spif_obj_t);
  755. extern spif_class_t spif_obj_get_class(spif_obj_t);
  756. extern spif_bool_t spif_obj_set_class(spif_obj_t, spif_class_t);
  757. extern spif_str_t spif_obj_show(spif_obj_t, spif_charptr_t, spif_str_t, size_t);
  758. extern spif_cmp_t spif_obj_comp(spif_obj_t, spif_obj_t);
  759. extern spif_obj_t spif_obj_dup(spif_obj_t);
  760. extern spif_classname_t spif_obj_type(spif_obj_t);
  761.  
  762. #endif /* _LIBAST_OBJ_H_ */
  763.